home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / maple / guide < prev    next >
Text File  |  1994-06-21  |  8KB  |  208 lines
  1.  
  2. Guidelines for contributing to the Maple share library.
  3. =======================================================
  4.  
  5. The purpose of the share library is to make Maple code and applications
  6. worksheets which have been developed by Maple users and groups other than the
  7. Maple company Waterloo Maple Software (WMS) freely available to Maple users.
  8.  
  9. For code and worksheets to be added to the share library, we require that
  10.  
  11. 1) you grant WMS a non-exclusive right to distribute your code or worksheet(s)
  12.    to any Maple user who requests it.  You may wish to include an authors
  13.    copyright notice in your code so that other parties cannot distribute it,
  14.    or sell it for profit.
  15.  
  16. 2) you hereby authorize WMS to modify your code or worksheet(s) as required,
  17.    for example, to correct bugs, and make changes required due to changes in
  18.    new versions of Maple
  19.  
  20. 3) you provide test file(s) (described below) that adequately test your Maple
  21.    code so that we can reasonably determine whether the code is working.
  22.  
  23. 4) you provide Maple style help file(s) (see below) as documentation for your
  24.    Maple code.
  25.  
  26. Points 1) and 2) are stated precisely in the file called "agree".
  27. Please read it, fill it out, sign it, and send or fax it to us at
  28.  
  29.   Dr. Michael Monagan
  30.   Institute for Scientific Computation, ETH Zentrum,
  31.   CH 8092 Zurich, Switzerland.
  32.   FAX: +41 (1) 262-3973
  33.   EMAIL: monagan@inf.ethz.ch
  34.  
  35. Code and worksheets must be sent by electronic mail to Dr. Monagan at the
  36. above address.  We insist on electronic mail because this this only feasible
  37. way in which we can contact you in case there is a problem with the code.
  38.  
  39. We also include some simple coding style conventions below.
  40.  
  41. Please understand that you are giving the code to the Maple community.
  42. You may not expect the WMS to pay any royalty or other monies for the code.
  43. However, WMS will NOT sell your code for profit.
  44. You may of course sell or distribute your code yourself.
  45.  
  46.  
  47. Test files
  48. ==========
  49.  
  50. The test file should read your code, and for each test, compare
  51. the actual answer computed with the answer that it should yield.
  52. If the comparison is okay, then the string "okay" should be printed.
  53. Otherwise you should print the bad result.
  54. Thus a typical test would be
  55.  
  56.   a := symmpoly([x,y,z],2):
  57.   if a = x*y + x*z + y*z then print(okay) else print(a) fi;
  58.  
  59. Notice that the correct result is included in the test file.
  60. And also that the output of a test which runs correctly is
  61. simply a sequence of okay's.
  62.  
  63. Please include the examples that you use in your help file as tests.
  64. In writing tests, you should also be aware of the following.
  65. Maple, and/or your code may return an answer that looks different,
  66. but is the same mathematically.  For example, Maple may return
  67. exp(2*x) instead of exp(x)^2 .  In your application, both answers
  68. may be acceptable.  Secondly, the output may come in a different
  69. order, e.g. [x^2+x+1, x^4+x+1] instead of [x^4+x+1, x^2+x+1].
  70.  
  71.  
  72. Coding conventions
  73. ==================
  74.  
  75. 1: Global variables
  76. -------------------
  77. Every programmer has his/her own coding style and we are not
  78. going to tell you how to program.  However, please do not use global
  79. variables in your procedures unless absolutely necessary.
  80. If necessary, please document them in the on-line help documentation.
  81.  
  82. The "mint" program will tell you which variables are global in
  83. your procedures and which names clash with Maple library functions.
  84. Look for global variables that you have forgotten to declare local.
  85.  
  86. 2: Naming conventions
  87. ---------------------
  88. Routines and global variables which are not meant to be directly accessed
  89. by the user, should be given "slash" names.  E.g. if your package is called
  90. foo, and you have a local routine which checks the input, you should call
  91. it `foo/check` and not check.  The macro facility will be useful here to
  92. avoid having to type `foo/check` throughout the code.  Simply put
  93.  
  94.   macro(foo = `foo/check`);
  95.  
  96. at the top of your code.  See ?macro for details
  97.  
  98. 3: Type checking
  99. ----------------
  100. Please include adequate type checking.  The type checking also serves
  101. as useful documentation for finding errors and understanding which cases
  102. your code is intended to handle.  For Maple V Release 2 and later versions,
  103. it is possible to declare the type of parameters.  For example, a routine
  104. foo which takes an algebraic expression a and an integer n as arguments can
  105. be written in this way
  106.  
  107.   foo := proc(a:algebraic, n:integer)
  108.  
  109. A routine foo which takes a list E of polynomials and a list X of variables as
  110. arguments can be written
  111.  
  112.   foo := proc(E:list(polynom),X:list(name))
  113.  
  114. 4: Miscellaneous
  115. ---------------
  116. Please do not use the old $ function for creating sequences.
  117. Please use instead the seq function.
  118. For example, instead of 'f(i)' $ 'i'=1..n use
  119.  
  120.   seq(f(i),i=1..n);
  121.  
  122. The seq function works like a for loop.  It doesn't require quotes and
  123. consequently is much simpler to use.  It is also more efficient.
  124.  
  125.  
  126. Documentation and Help files
  127. ============================
  128.  
  129. Remember, your code is only as useful as your documenation is clear.
  130. We require that you include Maple style help files which include a desciption
  131. of the user-level procedures and and global variables in your code, plus
  132. examples showing typical usage.
  133.  
  134. A TeX or LaTeX document is welcome as additional documentation.
  135. An Maple .ms worksheet (Release 2) showing how the package is used,
  136. and typical examples, is especially welcome.
  137.  
  138. To write a Maple help file for a function called say "symmpoly"
  139. one assigns an object of type TEXT to the name `help/text/symmpoly`.
  140. A TEXT object is a function whose arguments are Maple strings.
  141. For example, here is a help file for the symmpoly function
  142.  
  143.   `help/text/symmpoly` := TEXT(
  144.   `FUNCTION: symmpoly - generate the symmetric polynomials`,
  145.   `   `,
  146.   `CALLING SEQUENCES: symmpoly([x1,x2,...,xn]);  or`,
  147.   `                   symmpoly([x1,x2,...,xn],m);`,
  148.   `   `,
  149.   `PARAMETERS: x1,x2,...,xn - names`,
  150.   `            m - non-negative integer`,
  151.   `   `,
  152.   `SYNOPSIS:   `,
  153.   `- The call symmpoly([x1,...,xn],m) returns the symmetric polynomial`,
  154.   `  in the variables x1,...,xn (which may not necessarilly be distinct)`,
  155.   `  having total degree m`,
  156.   `- The call symmpoly([x1,...,xn]); returns a sequence of the symmetric`,
  157.   `  polynomials in x1, ..., xn for m = 0..n`,
  158.   `   `,
  159.   `EXAMPLES:   `,
  160.   `   `,
  161.   `> symmpoly([u,v,w,x],3);`,
  162.   `   `,
  163.   `                         u v w + u v x + u w x + v w x`,
  164.   `> symmpoly([x,y,z]);`,
  165.   `   `,
  166.   `                      1, x + y + z, x y + x z + y z, x y z`
  167.   ):
  168.  
  169.  
  170. When the user does  ?symmpoly  the text of your help file will
  171. be printed by Maple in the normal way. I.e. as
  172.  
  173.   FUNCTION: symmpoly - generate the symmetric polynomials
  174.  
  175.   CALLING SEQUENCES: symmpoly([x1,x2,...,xn]);  or
  176.                      symmpoly([x1,x2,...,xn],m);
  177.  
  178.   ... etc. ...
  179.  
  180.  
  181. How to create this TEXT object?
  182. -------------------------------
  183. Write the text for the help file in a file as you want it to appear
  184. for the user.  You may find it convenient to copy and edit a Maple help file.
  185. Under Unix, the C program "helptomaple" that you should find in the same
  186. place as "maple" is kept, can be used to create a TEXT object from a file
  187. of text.  For example
  188.  
  189.   helptomaple "help/text/symmpoly" < symmpolyhelp
  190.  
  191. outputs the TEXT object for symmpoly above, assigned to the name
  192. `help/text/symmpoly`.
  193.  
  194. Alternatively, in Maple V Release 2 and later versions of Maple, you can
  195. use the makehelp function from the Maple library.  Suppose the text you
  196. have for your help file is in the file foo.  Then in Maple do
  197.  
  198.   > readlib(makehelp): # load from the Maple library
  199.   > makehelp(topic, foo):
  200.   > save `help/text/topic`, fooTEXT;
  201.  
  202. The text file foo is read and converted into a TEXT object and assigned
  203. to the variable `help/text/topic`.  This has been saved into the file
  204. fooTEXT which you can now include in your Maple src code.  Then when the
  205. code loaded into Maple, the on-line help will also be there too.
  206.  
  207. Remember also to include the examples used in the help file in your test file!
  208.